Workbench Design

home *** CD-ROM | disk | FTP | other *** search

/ Workbench Design / WB Collection.iso / workbench werkzeuge / uhren & terminkalender / time / tbc / tbc.guide (.txt) < prev next >

Wrap

Amigaguide Document | 1996-04-07 | 34KB | 581 lines

@database "TBC - The User Guide" @font helvetica 11 @width 80 @node Main "TBC - The User Guide - Contents" TBC (Title Bar Clock) (also known as Threapwood's Big Clock) by David M Hollway -= Giftware =- Version 2.52 (8:55pm, 10th June 1994) Contents -------- @{"1) Introduction " Link intro} @{"2) Disclaimer " Link disc} @{"3) Features " Link features} @{"4) Installation " Link inst} @{"5) User Options " Link opts} @{"6) Tooltypes " Link tooltypes} @{"7) Contacting the Author" Link contact} @{"8) Version History " Link history} @{"9) Acknowledgements " Link sheep} @{"A) C Source-Code " Link C-source} @endnode @node intro "TBC - The User Guide - Introduction" 1) Introduction Earlier this year I downloaded from the @{"Aminet" link aminet} a program called HFK, written by Herbert West. HFK displays a simple clock in the left-hand end of the Workbench screen title-bar. Importantly, it uses the correct colour scheme (even on Kickstart 3.0), ie the same colours as the Workbench menus. I like HFK, because it is fully Kickstart 3.0 compatible, and simple. However, I had one tiny quibble with HFK. If I wanted to change the Workbench preferences, then I had to quit HFK, otherwise IPrefs displayed a requester saying "Please close all windows". This really annoyed me (because I often change screenmodes, and it was really tedious to quit & restart HFK each time). Then I hit upon the solution: I wrote a simple AmigaDOS script that would quit HFK and then re-start it after a short delay (to give IPrefs time to close & re-open the Workbench screen). I left the icon for this script on the Workbench, so all that I had to do was double-click the icon just before changing screenmode. An elegant solution. Or so I thought. But then one day I was idly reading the "Libraries" RKM (as one does :-) ), and I noticed a section about "notification" requests. So "Hey!" I thought, "why don't I write a program that will watch the ENV:Sys directory, and then when anything is written to this directory, close down & restart HFK?". So I did. That, too, seemed like an elegant solution at the time. But then I started thinking that this was a really kludgy solution (to have two programs running), and I decided to write a replacement for HFK. So here's the replacement: TBC! It's started off a a straightforward clock, but I've been carried away with adding new features, so that the result now is a clock program that does just about everything except cure bunions.. Incidentally, in case you're thinking "why doesn't this weirdo write a version of TBC that has no GUI to save memory?", I can tell you that the GUI on TBC takes only 4K. Are you *that* short of memory? @Endnode @node features "TBC - The User Guide - Features" 3) Features TBC is a great program (IMHO ;-) ) offering the following features: o will automatically hide itself to allow IPrefs to reset the screen o very low CPU load o fully WB3.0 compatible & enhanced o can display time in a variety of formats (24 hour, 12 hour etc) o colours used for display can be altered o requires OS 2.04 (v37) and above o Alarm Clock feature that will, at a configurable time, flash the screen/play a sample/beep/ launch a command (optional). o Fully configurable by means of @{"tooltypes" link tooltypes} or @{"GUI" link opts} * o ability to make tea/coffee/goats' milk at preset intervals o Ability to appear automatically on the active screen o will optionally chime every n minutes o can also display current date in choice of formats o as of v2.5, TBC can warn you if your Amiga's memory is running low * - feature no longer available.. registered users of TBC now get a *FREE* Slightly Confused Yak delivered to their home :-) Yes, yes, I know, it's a long feature list for a clock program, but I just can't stop adding to this program.. @EndNode @node disc "TBC - The User Guide - Legal Tripe" 2) Disclaimer Just in case there are any Americans reading this: This program is (C) 1994 David M Hollway. I take absolutely no responsibility for any damage or loss resulting from the use of this program. If TBC causes your computer to explode, wiping out 3/4 of your home country, it's not my fault. If TBC causes the value of your investment portfolio to plummet, it's not my fault. If TBC causes your aunt to break out in bright green spots and start speaking in tongues, again, it's NOT MY FAULT. "Amiga", "Kickstart", "Lorraine" and "Marketing" are (C) Commodore-Amiga, Inc. Never trust a dog with orange eyebrows. This program has been tested on the following Amiga systems: 1) A4000, 68EC030, 2MB CHIP, 6MB FAST, 85MB harddrive, OS 3.0 2) A4000, 68EC030, 2MB CHIP, 6MB FAST, 85MB harddrive, OS 2.04 3) A4000, 68EC030, 2MB CHIP, 6MB FAST, 120MB harddrive, OS 3.1 3) A4000, 68EC030, 2MB CHIP, 0MB FAST, 85MB harddrive, OS3.0 4) A4000, 68LC040, 2MB CHIP, 16MB FAST, 500MB harddrive, OS 3.1 5) A1200, 68EC020, 2MB CHIP, GVP 4MB FASTRAM + SCSI, 85MB harddrive, OS3.0 6) B2000, 68000, 1MB CHIP From this I'm assuming that TBC will work on any Amiga that runs 2.04 or greater. Obviously though a battery-backed realtime clock would help! :-) And a TV or other display device. Come to think of it, a voltage supply to the Amiga can be handy too.. If it doesn't work on your system, PLEASE let me know! I'm especially interested to hear from you if you've tried TBC (successfully or otherwise) on a 68000-based Amiga. See the end of this documentation for information on contacting me! This program may be used in military installations. But it can't be used by pacifist groups. So there. Probably because after using TBC you'll feel like head-butting your Amiga. @endnode @node inst "TBC - The User Guide - Installation" 4) Installation Easy. Just copy the "TBC" program (and its icon) to a suitable place on your disk. If you want TBC to load automatically when you boot, then place it in the "WBstartup" drawer of your "SYS:" partition or disk. That's it. TBC will now run using the default settings. To get the best out of TBC however, you should configure it using its @{"tooltypes" link tooltypes}. @endnode @node opts "TBC - The User Guide - Options" 5) User Options Click with the left mouse button on the TBC window to bring up the "TBC Options" window. Options are: "Foreground:" : click on a colour in this box, and the text of the TBC display will be rendered in this colour. "Background:" : click on a colour in this box, and the background of the TBC display will be rendered in this colour. "Use Pens:" : if this gadget is "ticked", then TBC will use the same colours as the Workbench menus. Under kickstart 2.0x, this means grey-on-black. Under 3.x, the menu colours can be set using the "Palette" preferences editor. "Time:" : select an option from this gadget. TBC can display the time in one of four formats: "6:34 pm" - 12 hour clock "6:34:00" - 12 hour clock with seconds display. "18:34" - 24 hour clock "18:34:00" - 24 hour clock with seconds display. "Date:" : As for "Time:" above, TBC can display the current date in a choice of formats. These are: "No Date" - Don't display the date "25.12.94" - Display date in dd.mm.yy format "12.25.94" - Display date in mm.dd.yy format If the date is displayed, then the clock display will, each time it updates, toggle between the current time and the current date. "Update (seconds)" : enter a number n in the text box next to this option, and the clock will be updated each time n seconds have elapsed. "Leap (danger!):" : If you select this option, then TBC will always appear on the currently active screen. *CAUTION* If TBC is displayed on a "non public" screen, and that screen is closed by an application, you MAY WELL crash the Amiga. Always make sure that you close TBC (or de-select this option) before closing the application. As an extra safeguard, TBC will not leap onto a screen unless: a) The screen is wider than 600 pixels (this rules out most games) b) The screen has a title. This is to prevent TBC leaping onto the screen opened by a screenblanker program, which would (as soon as you moved the mouse) crash the screenblanker. Programs whose screens TBC will leap on to include: Directory Opus v4.x Final Copy Final Writer PCTask Scribble! But sadly not DPaint, because it does naughty things with screen overlays etc, and doesn't have a title (it just prints "DPaint" in its title bar) Additionally, as of version 2.2 of TBC, I've added a small (1 second) delay before TBC "leaps" onto a newly active screen. I can't make this feature totally safe, but if you take care, it's very handy. *CAUTION ENDS* If this option is switched off, TBC will appear on the default public screen. "Alarm Hour:" : use this slider to set the hour at which the alarm will sound (in 24-hour format, 0 to 23). "Alarm Min:" : use this slider to set the minutes at which the alarm will sound, ie 0 to 59. "Chime each:" : if you enter a number other than 0 in this box then TBC will "chime" each time the "minutes past the hour" reach a multiple of that number. For example, entering 15 will cause TBC to chime at xx.00, xx.15, xx.30, and xx.45. "Alarm:" : This cyclebox determines the current state of the alarm feature. It can have the following settings: "No Alarm" - Alarm is OFF. "Flash" - Alarm is ON, and when alarm-time is reached, the screen will flash (and beep/play a sample if you have Workbench 3.x) repeatedly. "Command" - Alarm is ON, and when alarm-time is reached, a command or AmigaDOS script (see "Command:" below) will be launched. "Do Both" - The above two options combined. Once the alarm is sounding, it can be stopped by clicking with the left mouse button on the TBC display. If the options screen is being displayed when the alarm goes off, you can stop the alarm by setting this cycle-gadget to "No Alarm" "Command:" : If you enter a command in this text-box, and set the "alarm" gadget to "Command" or "Do Both", then when TBC sounds its alarm it will also run the command for you. You must give the command's name with its full path, for example: SYS:Utilities/Clock - will run the standard WB clock (why??) SYS:Tools/HDTools/Quarterback - will run a hard-disk backup program Note that this can either be a command, or an AmigaDOS script. If the latter, then the script must have its "script" protection bit set, for example type at a shell: 1.System3.0:> protect mydisk:myscript +S "If free mem is less than:" : Type a number into this text box, set the cycle gadget next to it to anything other than "ignore it", and lo! you will be warned by TBC when the amount of free memory (FAST + CHIP) falls below that number of Kilobytes. The options that can be set on the cycle gadget are: "ignore it" - doesn't do anything when memory is low "flash screen" - Uses the O/S DisplayBeep() function to flash the screen (or play a sample/beep if you're using 3.0) "show requester" - Displays a Recoverable Alert when memory is below n K. An Alert is always a chilling sight, so I'd recommend that you: a) remember not to panic when you see it, and b) use this option if you're expecting memory to get VERY low (such that neither a requester nor a beep can be used) "Use" : click here to close the options window, and use the current TBC settings. "Hide" : click here to hide the TBC window, to allow IPrefs to reset the WB screen. TBC will automagically re-appear after a short delay (see @{"TOOLTYPES" link tooltypes}). This is handy in situations where you've changed preferences, but you still have other applications open on the WB. This option allows you to hide TBC if it's re-appeared before you've closed down the other applications. "Quit" : click here to exit from TBC (why would you want to do this??) @endnode @node tooltypes "TBC - The User Guide - Tooltypes" 6) Workbench Tooltypes By default, TBC displays a 12-hour clock, in the current workbench menu colours, updating its display every second, with an alarm set for 12:00 midday. If you would like the initial options to differ from the defaults, you can specify the options by means of TOOLTYPES (if you're not sure how to do this, consult a Workbench manual) (or even a Haynes auto manual). TBC supports the following tooltypes: NONEWLOOK : this can be set to either 0 (to use the current WB colours), or 1 (to use the user-defined fixed colour scheme). DELAY : this is the number of seconds that will elapse between successive updates of the TBC display. Sensible values are between 1 and 60. Very silly values are 4000, 99 and "ni". FOREPEN : the pen to use for the writing on the display, ie with the default Workbench 2.x palette, a value of 1 would be black. BACKPEN : the pen to use for the background of the TBC display. Don't set this to the same value as FOREPEN, becauses you won't be able to see the display! *NOTE*: If the NONEWLOOK tooltype is either not specified, or set to 0, then the values of FOREPEN and BACKPEN will be ignored. FORMAT : set this to either 0, 1 or 2, to get one of the following TBC displays: 0 - time in format 6:34 pm 1 - time in format 6:34:00 2 - time in format 18:34 3 - time in format 18:34:00 IPREFSWAIT : Yes, by popular demand here's a tooltype that allows you to set the delay (in seconds) that TBC allows for IPrefs to reset the WB screen. For example, if you specify IPREFSWAIT=7, then when the screenmode/font etc of the WB is changed, TBC will hide its window for 7 seconds. A higher value of IPREFSWAIT than the default may be needed if IPrefs haKs a lot of work to do when resetting the WB, eg closing many drawers, using a 256-colour WB, etc. ** USERS OF TBC v1.x PLEASE TAKE NOTE ** This tooltype is now IPREFS rather than IPREF (note the extra 'S')! ALARM : This determines the initial state of the alarm feature. Valid options are: 0 - Alarm is OFF. 1 - Alarm is ON, and when alarm-time is reached, the screen will flash (and beep/play a sample if you have Workbench 3.x) repeatedly. 2 - Alarm is ON, and when alarm-time is reached, a command or AmigaDOS script (set using ALARMRUN) will be launched. 3 - 1 & 2 combined. ALARMHOUR : The hour of the alarm, in 24-hour format, eg valid options range from ALARMHOUR=0 to ALARMHOUR=23. ALARMMIN : This tooltype sets the alarm minutes; valid options range from ALARMMIN=0 to ALARMMIN=59. ALARMRUN : This can be used to specify a command to be run when the alarm is activated. For example: ALARMRUN=SYS:Prefs/Palette For more information, @{"click here" link opts 119}. CHIME : This is the chime setting (see @{"section 4" link opts 93}) eg: CHIME=15 DATE : This is the date format setting, eg: DATE=0 means no date is displayed DATE=1 means date is displayed as dd.mm.yy DATE=2 means date is displayed as mm.dd.yy SCREENLEAP : Set this option to enable/disable screen leaping. eg: SCREENLEAP=1 or SCREENLEAP=0 MEMWARN : This is the amount of memory (in K) below which TBC will alert you.. WARNTYPE : ..and this is how TBC will alert you. Valid options are: WARNTYPE=0 means "do nothing" WARNTYPE=1 means "flash the screen once" WARNTYPE=2 means "display a requester" WARNTYPE=3 means "display an alert" See @{"User Options" link opts 168} for more details! In addition you'll need to specify the tooltype DONOTWAIT if you've placed TBC in your SYS:WBStartup drawer. If you don't, then you'll see a requester saying "TBC has not returned - Shall I wait some more?" every time you reboot. This is a real pain in the proverbials, and is caused not by TBC but by Kickstart. @endnode @node contact "TBC - The User Guide - Contacting the Author" 7) Contacting the Author This small trifle has been released as GIFTWARE. This means that if you use and like the program, the author (that's me) would welcome a gift from you. Please note that this is not compulsory - I hate "Crippleware", so I've released this fully working version of TBC (ha! the program has hardly any features to begin with.. if I crippled some features the program wouldn't do anything :-) ) and I'd love to get a gift from people. This gift can be *anything* you feel the program is worth.. if nothing else, send me some e-mail (address below), a postcard of your home town, or even write to me! I'm not expecting anybody to send me a 4000-040, but you never know... here's some suggestions for gifts anyway :-) - a funny/ funky / impressive Sound/Noise/ProTracker module - ditto, but in MED/ OctaMED format - a humorous anecdote - a postcard - a letter to say "thank you" - an e-mail message - vast amounts of money - free beer (here's hoping...) Even if you do nothing else, I'd ask you to dim your monitor to half-brightness in salute to Commodore, and what might have been. If you are Swiss I'd especially like to hear from you, as I'm going to that wonderful country for a year (as of July 1994). I can be contacted in the following ways (in order of preference): by e-mail: I have two internet addresses, so mail sent to either dmh11@tower.york.ac.uk or dmh-a@minster.york.ac.uk should reach me. by snail-mail: Bit tricky this one, because of the above mentioned Swiss trip. Probably the best address to send mail to is: DM Hollway, Langwith College, University of York, Heslington, York, YO1 5DD by telepathy: Just concentrate Anybody interested can get the full source-code for TBC by writing to me, and enclosing sufficient money to cover postage from the UK to their country. @endnode @node history "TBC - The User Guide - History" 8) Version History (versions prior to 2.0 removed to save space on my hard drive) Version 2.0: Fourth public release. (8th May 1994) Added "Alarm Run" feature and ALARMRUN tooltype. Cleaned up & optimised code somewhat. It may not be smaller, but it's neater! Version 2.01: Never released. Tiny, tiny bug fix. Made BOTH colons "tick" on clock display. Happy, Fergus? :-) Altered user interface layout slightly. (transposed ALARM and UPDATE areas, if you must know) Version 2.1: Fifth public release (15th May 1994) Added CHIME, DATE and LEAP options (and tooltypes) Altered user interface layout to accomodate the new options. Drastically cleaned up & optimised code, with the result that this new version is only about 500 bytes larger than v2.0, despite the new features. Version 2.2: Sixth public release (17th May 1994) Whoops.. there were a couple of fairly major bugs in version 2.1 - occasional screen corruption occurred if the clock used a proportional font. That's now fixed (I hope!). TBC has now been tested with fonts up to 24pt. If you have to use a bigger font than that, then your eyes need seeing to! Improved the ALARM function; you can now choose whether TBC beeps, runs a command, or both when the alarm goes off. (see 'Options' and 'Tooltypes'). Replaced RectFill() calls with SetRast(), saving a few bytes. Code should now be bug-free. I bet I'll regret saying that! Version 2.2.1: Yes.. I do regret saying that! There was a tiny bug in TBC v2.2 that caused the ALARM tooltype to be ignored. That's now fixed. And I've updated the documentation properly too. Version 2.5: Hmm... a couple of silly bugs in previous versions :-( In fact even as I write this I've noticed another bug! Just a moment.... ...there, that's fixed the swine. As I was saying: in this version I've added a "memory warning" feature, and also TBC will now report 12:00am as 12:00 am, whereas in all previous versions it reported it as 0:00am. In addition, previous versions changed from "am" to "pm" at 1:xx, rather than 12:xx. Many thanks to the two alert people in the U.S who spotted and reported those bugs! In fact I've just spotted another bug.. the ALARM tooltype STILL isn't being recognised properly! How very embarassing, I thought I'd fixed it in 2.2.1! Oh well, it's definitely fixed now. Version 2.51: Well, my beta-testers have failed miserably :-) NOBODY reported the fact that in 2.5 the entire alarm feature didn't work! Many thanks to Slingshot of Dimentia UK, who was the only person observant enough to notice this! Duh.. It's a good job I didn't release 2.5 publicly :-) Version 2.52: Well this bug's got me confused.. for some reason if I set the "seconds" string to _5_ spaces in 24hour mode, ("16:34") then the current hour gets printed instead of the five spaces.. but if I set it to _6_ spaces, it gets printed as expected! Anybody out there have an idea why this is the case? Anyway, it's fixed now! @endnode @node Aminet "TBC - The User Guide - Aminet" What is Aminet? The "Aminet" is a vast collection of Amiga software. Many (academic) institutions around the world store copies (or "mirrors") of the Aminet collection. To access Aminet, use the "FTP" program (available on most UNIX systems, etc) to connect to any of the following sites: src.doc.ic.ac.uk ftp.uni-paderborn.de wuarchive.wustl.edu ftp.funet.fi (and many others that I can't remember). @endnode @node sheep "People I wish to thank" I wish to thank the following persons, groups, and ideas, without whom I would never have been inspired to write and update TBC.. Herbert West (author of HFK) Slingshot of Dimentia UK, who yelled at me when I missed him out of the first draft of these docs. Sorry m8.. Fergus O'Hea Paul Hollow Jane Williams Edd Dumbill Eric Haines William "Wim" Roose Matthew "Small White Block Thingies!" Marcus & Dylan "purple hair?" Owen All the Amiga crew on Monochrome (138.40.17.1) ...and a BIG thank-you to Dave Haynie, John Toebes, Andy Finkel, and all the real geniuses who struggled against so much adversity (and against Commodore Management) to bring us the glorious AMIGA! May Messrs. Gould & Ali never be allowed to control a company again! While I'm at it, I'll give a quick mention to the many wonderful people who've written to me to offer praise, bug reports, suggestions, criticisms and so on. Thankyou, everybody! Dave Dustin : who suggested the option to set alarm behaviour Geoff Seeley : who told me about a silly bug Chris Poirier : Sorry Chris, still no multiple alarms.. Byron Montgomerie & J. Parcone : OK, I've fixed the 12:00am = 0:00am bug James Atwill : for suggesting a seperate GUI.. is the extra 4K that TBCs GUI takes really *that* important? Scott Rowland : for asking about the TBC-on-a-private-screen & Rodney Hester problem.. read the caveat in section 5! Roland Mcintosh : for his kind words about TBC Matt Prechota : ditto.. and I don't know what you mean about the font change handling problem? Russell Woodford : for being the first person to remind me that a clock should change from am to pm at 12:00, NOT 1:00 James Dunne : for suggesting a memory meter feature.. ..phew! That's it I think.. If I've omitted anybody I'm sorry! Other influences.. feel free to contact me to discuss them: Monty Python Terry Pratchett Christianity Craig Shaw Gardner Red Dwarf Star Trek & ST-DS9 Gary Larson Ren & Stimpy And I can strongly recommend the following programs to any Amiga enthusiast: SwazInfo by David Swasbrook CycleToMenu F. Giannici PatchPointer Steve Lemieux StatRAM ? KingCON David Larsson MonEd ? DropBox Steve "Meef" Anichini Garshneblanker Michael D Bayne NewEdit Uwe Rohm AppTrash Johan Stenarson AltTab Gerard Cornu StarClick ? SnoopDOS Eddy Carroll Iconian Chad Randall (BRILLIANT Icon Editor!) UnixDirsII Martin Scott @endnode @node pubsc "Everything you ever wanted to know about Public Screens" A "public" screen is an Intuition screen on which applications other than the one that opened the screen can open their windows. Prior to Kickstart 2.0 (v36), the only "public" screen was the Workbench; now, however, there can be any number of public screens open at a given time. TBC shouldn't really be able to open on non-public screens, and so it employs some trickery to do so. Which is why it's dangerous to close these screens whilst TBC is open on them - well-behaved applications that open public screens (for example, Directory Opus) will detect that there are "alien" windows open on their screen and act accordingly. @endnode @node C-source "IMPORTANT: Read this before even CONTEMPLATING editing the source!" Notes about the Source-code for TBC ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The file "TBC_252.c" in this archive is the source-code for version 2.52 of The source is in C, and it should compile with either DICE or SAS/C 6,50. I'm sorry that it has no comments whatsoever in it; if anything in it is unclear please contact me and I'll try and explain it. It's a major failing of mine that I don't comment my programs. Hey, *I* know what they do :-) As regards usage of this sourcecode, you may use sections of it in your own programs. If you release such a program publicly, please acknowledge me somewhere in the documentation to your program. If you modify this code, re-compile it, and then distribute it publicly, please send me a copy of the new program AND acknowledge me in the documentation - something along the lines of: "Super-TBC version 99.5 by John Doe, original version by DM Hollway" ..will be fine. I'm quite happy for people to release their own "improved" versions of TBC, so long as these conditions are followed. If you have any queries about these conditions, or indeed about TBC itself, please feel free to contact me. @endnode